JBoss.orgCommunity Documentation
The Mobicents XML Document Management Server (XDM Server) is part of the Mobicents SIP Presence Service; it is the first free and open source implementation of an XML Document Management Server as defined in the Open Mobile Alliance (OMA) XML Document Management v1.1 specification. This functional element of next-generation IP communication networks is responsible for handling the management of user XML documents stored on the network side, such as presence authorization rules, contact and group lists (also known as resource lists), static presence information, and much more.
The SIP interface partially implements the XCAP Diff Event IETF draft, version 3. Subscriptions to a single document or usage by an entire application are supported. However, these differing usages do not extend to the single-XML element or attribute value level. Regarding the notifications, the diff-processing subscription parameter, if present, is ignored, and patching of content is not available at the moment, which means that only the document etags, new and/or old, will be provided.
The XDM Server comprises the following functional elements:
Functional Elements of the XDM Server
The XDM Server data source is where all user XML documents are stored. Information related to the server itself is also stored in this element along with the user's provisioned data
The data source also handles subscriptions to updates on specific documents, or complete XCAP application usages.
The aggregation proxy is responsible for handling an XDM client's XCAP requests
The authentication proxy is responsible for authentication of the user related with each XCAP request handled.
This element includes the XCAP Server logic to process an XCAP request and return a proper response, including authorization for the authenticated user.
This element, using the SIP protocol, is responsible for handling subscriptions to documents managed by the XDM. Its functions include the authentication and authorization of a subscription, attachment to update events on specific documents or application usages, and the sending of notifications when documents change.
The Mobicents XDM Server comes pre-configured for an XCAP root of http://<hostname>:8080/mobicents, hostname being the host/IP used to start the server (127.0.0.1 by default). It is possible to change the host, the port and the last path segment:
Rename $JBOSS_HOME/server/<server_profile>/deploy/mobicents.war
to the desired last path segment in the XCAP root (e.g. rename to xcap-root.war for an XCAP root of http://<hostname>:8080/xcap-root). The <server_profile> is the server configuration/profile used in the underlying JBoss AS, by default it is default
Edit $JBOSS_HOME/server/<server_profile>/deploy/http-servlet-ra-DU-*.jar/META-INF/deploy-config.xml
. Uncomment and set custom servlet name again to the desired last path segment in the XCAP root.
Edit the properties in file $JBOSS_HOME/server/<server_profile>/deploy/mobicents-xdms/3-beans/configuration/xdms/META-INF/jboss-beans.xml
. Note that the xcapRoot has a leading /. Also note that for the Integrated Server the path segment mobicents-xdms is mobicents-sip-presence.
This configuration part can also be done through JMX, using the MBean named org.mobicents.slee:sippresence=XDMServerConfiguration. The configuratian changes through JMX are not persistent.
There are other configurable features related with the XCAP Interface:
Edit the properties in file $JBOSS_HOME/server/<server_profile>/deploy/mobicents-xdms/3-beans/configuration/xdms/META-INF/jboss-beans.xml
. Note that for the Integrated Server the path segment mobicents-xdms is mobicents-sip-presence.
This configuration part can also be done through JMX, using the MBean named org.mobicents.slee:sippresence=XDMServerConfiguration. The configuratian changes through JMX are not persistent.
The Mobicents XDM Server SIP Interface can be configured regarding several features, such as subscription timers:
Edit the properties in file $JBOSS_HOME/server/<server_profile>/deploy/mobicents-xdms/3-beans/configuration/sip-event/subscription/META-INF/jboss-beans.xml
. Note that for the Integrated Server the path segment mobicents-xdms is mobicents-sip-presence.
This configuration part can also be done through JMX, using the MBean named org.mobicents.slee:sippresence=SipEventSubscriptionControl. The configuratian changes through JMX are not persistent.
XCAP interface is public, used by users to manage their information such as buddy list, presence authorization rules, etc. thus it needs to enforce user authentication. To do the user authentication, the server relies on the User Profile Enabler managed data, such as the users passwords, and this information must be provisioned, this can be done in two ways, both requiring the server to be running:
Users can be added/removed through the MBean named org.mobicents.slee:userprofile=UserProfileControl
Users can be added/removed through adding/removing rows of the table named MOBICENTS_SLEE_ENABLER_USERPROFILES.
The XDM Server allows the usage of asserted user IDs, though the usage of X-3GPP-Asserted-Identity
or X-XCAP-Asserted-Identity
header in the XCAP request. If the XDM Server is directly exposed to public this feature should be disabled, through the configuration of the XCAP Interface.
What is an XCAP Application Usage?
"Each XCAP resource on a server is associated with an application. In order for an application to use those resources, application specific conventions must be specified. Those conventions include the XML schema that defines the structure and constraints of the data, well-known URIs to bootstrap access to the data, and so on. All of those application specific conventions are defined by the application usage." RFC 4825
Each XCAP Application Usage defines:
The AUID used in XCAP URIs to point to a specific App Usage, e.g. resource-lists
in http://xdms.mobicents.org:8080/xcap-root/resource-lists/users/sip:user@mobicents.org/index
Defines the namespace of elements/attributes without prefix in XCAP URIs, usually it matches the default namespace of the XML Schema for documents of the App Usage,e.g. in http://xdms.mobicents.org/xcap-root/pres-rules/users/sip:eduardo@mobicents.org/index/~~/watcherinfo/watcher-list/watcher[@id="8ajksjda7s"], selection is made on watcher
elements with the pres-rules default document namespace.
MIME Type used when exchanging XML content.
The XML Schema to validate documents; Data constraints, which are impossible to validate with XML Schema, e.g. one element value must be a ISO country name (2 char) that belongs to Europe.
Semantic definition on documents content, used by applications filling data, not validated by servers.
What is the document name for each user? Are there global documents under a specific name? XCAP Clients usually forget to follow these!
One request may update other documents as well, e.g. global/index document in rls-services, a composition of all users/*/index service
elements.
What each user can read or write?
The Mobicents XDM Server includes the following XCAP application usages:
The Mobicents XDM Server XCAP Application Usages are implemented with a few simple Java classes and some meta data, it is very easy to develop additional ones.
Each Application Usage is represented by a Java class extending the abstract org.mobicents.xdm.server.appusage.AppUsage
class:
package org.mobicents.xcap.server.slee.appusage.presrules;
// ...
public class PresRulesAppUsage extends AppUsage {
public static final String ID = "pres-rules";
public static final String DEFAULT_DOC_NAMESPACE = "urn:ietf:params:xml:ns:pres-rules";
public static final String MIMETYPE = "application/auth-policy+xml";
private static final String AUTH_ONLY_DOCUMENT_NAME = index;
public PresRulesAppUsage(Validator schemaValidator) {
super(ID,DEFAULT_DOC_NAMESPACE,MIMETYPE,schemaValidator,AUTH_ONLY_DOCUMENT_NAME);
}
}
Methods for data constraints and resource interdependencies can be overriden:
public void checkConstraintsOnPut();
public void checkConstraintsOnDelete();
public void processResourceInterdependenciesOnPutDocument();
public void processResourceInterdependenciesOnDeleteElement();
//...
RLSServicesAppUsage and ResourceListsAppUsage are good examples on how to implement those methods.
Multiple constructors exposed to provide your App Usage XML Schemas Validators and/or Authorization Policies:
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype,
Validator schemaValidator, String authorizedUserDocumentName);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype,
Validator schemaValidator, AuthorizationPolicy authorizationPolicy);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype,
Validator schemaValidator, Validator uniquenessSchemaValidator,
String authorizedUserDocumentName);
public AppUsage(String auid, String defaultDocumentNamespace, String mimetype,
Validator schemaValidator, Validator uniquenessSchemaValidator,
AuthorizationPolicy authorizationPolicy);
Default Authorization Policy if custom is not provided, an user can read/write his/her own documents, with the specified document name.
An implementation of an object factory is required, which should extend class named org.mobicents.xdm.server.appusage.AppUsageFactory
:
package org.mobicents.xcap.server.slee.appusage.presrules;
// ...
public class PresRulesAppUsageFactory implements AppUsageFactory {
private Schema schema = null;
public PresRulesAppUsageFactory(Schema schema) {
this.schema = schema;
}
public AppUsage getAppUsageInstance() {
return new PresRulesAppUsage(schema.newValidator());
}
public String getAppUsageId() {
return PresRulesAppUsage.ID;
}
public AppUsageDataSourceInterceptor getDataSourceInterceptor() {
return null;
}
}
The factory is used to maintain a cache/pool of your app usage objects, since XML Schema Validator are expensive objects to create.
The factory can also provide a DataSource Interceptor, which will be used to generate a document on request (for instance the oma-xcap-directory generates the user document for each request).
A deployer to load/unload the App Usage into the XDM Server, it should extend class named org.mobicents.xdm.server.appusage.AppUsageDeployer
:
package org.mobicents.xcap.server.slee.appusage.presrules;
// ...
public class PresRulesAppUsageDeployer extends AppUsageDeployer {
@Override
public AppUsageFactory createAppUsageFactory(Schema schema) {
return new PresRulesAppUsageFactory(schema);
}
@Override
public String getSchemaRootNamespace() {
return PresRulesAppUsage.DEFAULT_DOC_NAMESPACE;
}
}
Multiple XML schema files may be combined, starting point is the namespace returned by getSchemaRootNamepsace()
, which not always is the same as the app usage's default doc namespace.
The deployer is actually a JBoss Microcontainer Bean, and a jboss-beans.xml
file is needed in the META-INF directory of the app usage jar:
<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:jboss:bean-deployer:2.0">
<!-- Registers the APP USAGE DEPLOYER AS JBOSS MICROCONTAINER BEAN -->
<bean name="Mobicents.XDMS.AppUsage.Deployer.PresRules" class="org.mobicents.xcap.server.slee.appusage.presrules.PresRulesAppUsageDeployer">
<!-- this app usage depends on app usage management only -->
<depends>Mobicents.XDMS.AppUsageManagement</depends>
</bean>
</deployment>
A unique bean “name” is need, and of course the “class” name of the Deployer, nothing else needs to be changed.
The Application Usage classes and metadata should be packed in a jar, with a structure similar to:
example-appusage.jar
|-META-INF
|---jboss-beans.xml (jboss mc bean descriptor)
|-org
|---mobicents
|------xdm
|---------server
|------------appusage
|---------------example
|------------------ExampleAppUsage (app usage class)
|------------------ExampleAppUsageFactory (factory class)
|------------------ExampleAppUsageDeployer (deployer class)
|------------------ExampleAuthorizationPolicy (optional auth policy class)
To deploy simply drop the jar in $JBOSS_HOME/server/default/deploy/mobicents-xdms(or mobicents-sip-presence)/3.beans/appusages
. To undeploy simply delete the jar.
What about the XSD file(s)? Simply copy to the xsd
directory inside the appusages
directory, a few limitations on multiple XSD files combination:
References between namespaces on different files must be done through import
element.
A namespace can only be defined within a single xsd file.
Contribution of additional App Usages are welcome, but a few rules apply:
Implements a standard app usage, defined by IETF, OMA or other standard organization.
A document is provided defining the app usage. This document may be the one defined by the standard organization.
The app usage jar and XSDs are ready to deploy, i.e., if the app usage was already tested and works.
Includes JUnit basic tests to validate put/get and delete of a document, similar to the ones included in RLS Services app usage source code, see the ones in the SVN, at trunk/servers/sip-presence/xdm/server/appusages/rls-services/tests
. If the app usage defines data constraints or resource interdependencies then these should be validated by tests too.